Como crear documentacion de una API Rest con Swagger Springfox version: 2.9.2

Para utilizar Swagger tenemos que añadir las siguientes dependencias en el archivo pom.xml:

<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger2</artifactId>
    <version>2.9.2</version>
</dependency>
<dependency>
    <groupId>io.springfox</groupId>
    <artifactId>springfox-swagger-ui</artifactId>
    <version>2.9.2</version>
</dependency>

Una vez tenemos definidas las dependencias dentro de la carpeta configuration de nuestro proyecto creamos un archivo SwaggerSpringFoxConfig.java, con el siguiente contenido:

package main.configuration;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import springfox.documentation.builders.ApiInfoBuilder;
import springfox.documentation.builders.PathSelectors;
import springfox.documentation.builders.RequestHandlerSelectors;
import springfox.documentation.service.ApiInfo;
import springfox.documentation.service.Contact;
import springfox.documentation.spi.DocumentationType;
import springfox.documentation.spring.web.plugins.Docket;
import springfox.documentation.swagger2.annotations.EnableSwagger2;


@Configuration
@EnableSwagger2
public class SwaggerSpringFoxConfig {

	@Bean
	public Docket api() {

		return new Docket(DocumentationType.SWAGGER_2)
			.apiInfo(getApiInfo())
			.select()
			.apis(RequestHandlerSelectors.basePackage("main.controllers"))
			.paths(PathSelectors.any())
			.build();
	}

	private ApiInfo getApiInfo() {

		return new ApiInfoBuilder()
			.title("Skill Matrix")
			.version("1.0.0")
			.contact(
				new Contact("Softwareone", "https://www.softwareone.com/es-es/", "manuel.bascoy@softwareone.com"))
			.build();

	}
}

Aqui tenemos que modificar RequestHandlerSelectors.basePackage("main.controllers") en vez de main.controllers tendriamos que poner el paquete donde estan los controladores de nuestra API Rest

y en la funciona getApiInfo cambiaríamos .title, .version y .contact para poner nuestros datos

Las anotaciones que podemos usar con Swagger para documentar nuestra API son las siguientes:

Codigos ejemplo:

@GetMapping("/members")
@ApiOperation(value = "Returns a list with all members.", notes = "The list of members returned includes all the skills and languages related to the member.")
@ApiResponses(value = { @ApiResponse(code = 200, message = Constants.CODE200, response = MemberData.class),
                @ApiResponse(code = 400, message = Constants.CODE400),
                @ApiResponse(code = 500, message = Constants.CODE500) })
public List<MemberData> getMembers(
                @ApiParam(value = "[Optional] idSkill param for skill query.", example = "12") @RequestParam(required = false) Long idSkill,
                @ApiParam(value = "[Optional | Requires idSkill] idSkillLevel param for skill level query, idSkill param required.", example = "12") @RequestParam(required = false) Long idSkillLevel,
                @ApiParam(value = "[Optional] name param for name query.") @RequestParam(required = false) String name,
                @ApiParam(value = "[Optional] role param for job query.") @RequestParam(required = false) String role,
                @ApiParam(value = "[Optional] idLanguage param for language query.", example = "12") @RequestParam(required = false) Long idLanguage,
                @ApiParam(value = "[Optional | Requires idLanguage] idLanguageLevel param for language level query, idLanguage param required.", example = "12") @RequestParam(required = false) Long idLanguageLevel)
                throws ValidationException {
        List<MemberData> listMemberData = memberQueryService.getAll(idSkill, idSkillLevel, name, role,
                        idLanguage, idLanguageLevel);
        return listMemberData;
}

@ApiModel(description = "Stores all the attributes required for the /api/members endpoint.")
public class MemberData {

	@ApiModelProperty(position = 0, hidden = true)
	@JsonInclude(Include.NON_NULL)
	private Long id;

@ApiOperation: Permite dar un titulo al endpoint con value y una descripcion con notes. Esta anotacion se coloca antes de la funcion del controlador.
@ApiResponses: Lista de anotaciones @ApiResponse para documentar los posibles codigos de respuesta del endpoint. Se coloca antes de la funcion del controlador.
@ApiResponse: Esta anotacion va dentro de @ApiResponses, se utiliza una etiqueta @ApiResponse por cada codigo que queramos documentar, usamos code para indicar el codigo, message para indicar un mensaje y response por si queremos indicar una clase concreta que devuelva esa solicitud.
@ApiParam: Esta anotacion se utiliza para documentar los parametros de la funcion, se coloca justo antes del parametro en cuestion, usamos value para indicar una descripcion y podemos usar example para indicar un valor de ejemplo que tomará dicho parametro, la opcion example se puede utilizar para prevenir un bug que tiene el swagger.
@RequestParam: Podemos utilizar esta anotacion para indicar si un parametro es obligatorio o no
@ApiModel: esta anotación se puede utilizar en clases (en dto o en clases del modelo) para documentar cual es su uso. la anotacion se coloca antes de la definicion de la clase
@ApiModelProperty: esta anotacion nos permite definir caracteristicas concretas para cada atributo de una clase, podemos utilizarla para indicar el orden que tendra en la documentacion o para indicar si ocultar el atributo concreto en la documentacion, esta anotacion se coloca antes del atributo dentro de la clase.

Spring | Swagger | Documentacion

Documentacion con Swagger SpringFox